---
title: 会话
description: Persist multi-turn conversation history so agents can resume context across runs.
---

import { Code } from '@astrojs/starlight/components';
import sessionsQuickstart from '../../../../../../examples/docs/sessions/basicSession.ts?raw';
import manageHistory from '../../../../../../examples/docs/sessions/manageHistory.ts?raw';
import customSession from '../../../../../../examples/docs/sessions/customSession.ts?raw';
import sessionInputCallback from '../../../../../../examples/docs/sessions/sessionInputCallback.ts?raw';

Sessions 为 Agents SDK 提供了一个**持久化内存层**。向 `Runner.run` 提供任何实现了 `Session` 接口的对象，其余由 SDK 处理。当存在 session 时，runner 会自动：

1. 获取先前存储的对话项，并在下一轮对话前将其预置。
2. 在每次运行完成后，持久化新的用户输入和助手输出。
3. 保持该 session 可用于后续轮次，无论是用新的用户文本调用 runner，还是从中断的 `RunState` 恢复。

这免除了手动调用 `toInputList()` 或在轮次之间拼接历史的需要。TypeScript SDK 自带两个实现：用于 Conversations API 的 `OpenAIConversationsSession`，以及用于本地开发的 `MemorySession`。由于它们共享 `Session` 接口，您可以插入自己的存储后端。除 Conversations API 外的更多灵感，可查看 `examples/memory/` 下的示例 session 后端（Prisma、文件存储等）。

> 提示：要运行本页中的 `OpenAIConversationsSession` 示例，请设置 `OPENAI_API_KEY` 环境变量（或在构造 session 时提供 `apiKey`），以便 SDK 可以调用 Conversations API。

---

## 快速上手

使用 `OpenAIConversationsSession` 与 [Conversations API](https://platform.openai.com/docs/api-reference/conversations) 同步内存，或替换为任何其他 `Session` 实现。

<Code
  lang="typescript"
  code={sessionsQuickstart}
  title="使用 Conversations API 作为会话内存"
/>

复用同一个 session 实例可确保每一轮开始前，智能体都能收到完整对话历史，并自动持久化新增条目。切换到不同的 `Session` 实现无需其他代码改动。

---

## Runner 如何使用 sessions

- 在每次运行之前：检索 session 历史，将其与新一轮输入合并，并将合并后的列表传给智能体。
- 对于非流式运行：一次调用 `session.addItems()` 即可持久化该轮的原始用户输入和模型输出。
- 对于流式传输运行：先写入用户输入，并在该轮完成后追加流式输出。
- 当从 `RunResult.state` 恢复时（用于审批或其他中断），继续传递同一个 `session`。恢复的该轮会被添加到内存中，而无需重新准备输入。

---

## 历史的查看与编辑

Sessions 暴露了简单的 CRUD 助手，便于构建“撤销”“清空聊天”或审计等功能。

<Code lang="typescript" code={manageHistory} title="读取与编辑已存储条目" />

`session.getItems()` 返回已存储的 `AgentInputItem[]`。调用 `popItem()` 可移除最后一条——在重新运行智能体前，适用于用户更正。

---

## 自带存储

实现 `Session` 接口，用 Redis、DynamoDB、SQLite 或其他数据存储来支撑内存。只需五个异步方法。

<Code
  lang="typescript"
  code={customSession}
  title="自定义内存内的 session 实现"
/>

自定义 session 可用于强制执行保留策略、添加加密，或在持久化前为每次对话轮次附加元数据。

---

## 控制历史与新条目的合并方式

当以 `AgentInputItem` 数组作为运行输入时，提供 `sessionInputCallback` 以确定性地将其与存储的历史合并。runner 会加载现有历史，在**模型调用之前**调用您的回调，并将返回的数组作为该轮的完整输入交给模型。此钩子非常适合裁剪旧条目、去重工具结果，或仅突出您希望模型看到的上下文。

<Code
  lang="typescript"
  code={sessionInputCallback}
  title="使用 sessionInputCallback 截断历史"
/>

对于字符串输入，runner 会自动合并历史，因此该回调是可选的。

---

## 审批与可恢复运行的处理

人工干预流程通常会暂停一次运行以等待审批：

```typescript
const result = await runner.run(agent, 'Search the itinerary', {
  session,
  stream: true,
});

if (result.requiresApproval) {
  // ... collect user feedback, then resume the agent in a later turn
  const continuation = await runner.run(agent, result.state, { session });
  console.log(continuation.finalOutput);
}
```

当您从先前的 `RunState` 恢复时，新的一轮会追加到同一条内存记录中，从而保留单一的对话历史。人工干预（HITL）流程完全兼容——审批检查点仍通过 `RunState` 往返，而 session 负责保持完整的对话记录。
